docs(website): docs architecture + theming section (docs PR 1 of 4) - #60

11-task plan covering the 9 new MDX pages + nav extension + /docs
index hub refresh:

- Task 1: Extend _nav.ts (1 section → 2) + refresh /docs hub
- Task 2: Getting Started > Concepts page (mental-model overview)
- Task 3: Theming Overview (concept page, ASCII-art layered diagram)
- Task 4: Theming > Pick a theme (Excel vs Material 3)
- Task 5: Theming > Override tokens (the override story)
- Task 6: Theming > Light / dark switching
- Task 7: Theming > Density switching
- Task 8: Theming > Custom themes
- Task 9: Theming > Tailwind v4 + CSS-in-JS
- Task 10: Theming > Token reference (canonical 24-token table)
- Task 11: Final verification (build + test + typecheck + prettier
  + visual sanity)

Each MDX page has full content inline so the implementer subagent
can transcribe rather than author. Prettier discipline on every
commit step. ASCII-art diagram chosen over inline SVG to avoid
JSX-in-MDX complexity for v0.0.x.

Decided to drop the empty-sections-in-nav approach: Grid /
Streaming / API Reference / Examples sections are added in PR 2 /
PR 3 of the docs arc when their content lands. Sidebar feels
"complete" via the /docs index hub's "Coming soon" copy.

10-11 commits in this PR depending on whether the spec/plan commits
count. Each commit ships one user-visible page.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>

Extends apps/website/app/docs/_nav.ts from one section (Getting
Started) to two (Getting Started, Theming). Adds the 8 theming
nav entries pointing at pages that subsequent commits in this PR
create. Also adds the Concepts entry under Getting Started.

Refreshes apps/website/app/docs/page.mdx from the prior 8-line
stub into a section-card hub. The hub describes the documented
sections (Getting Started, Theming) + the deferred ones (Grid,
Streaming, API Reference, Examples — landing in subsequent docs
PRs). Honest about coverage rather than promising more than ships.

Part 1 of pretable docs PR 1 (theming section + concepts). The
content pages land in subsequent commits in this PR; the build
passes here because Next.js doesn't validate href targets at
build time.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>

One-page mental-model overview of pretable's three-layer architecture:
engine (@pretable/react), theming layer (@pretable/ui), streaming
(deferred for v0.0.x). Documents the two-namespace coexistence
pattern, the three runtime axes (theme, density, light/dark), and
the pre-1.0 instability caveat.

Cross-links to Theming Overview, Override tokens, Token reference,
and the streaming overview (lands in PR 3 of the docs arc).

Part 2 of pretable docs PR 1.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>

The theming model documented as three cooperating CSS layers:
theme tokens (Layer 1), grid.css chrome selectors (Layer 2),
consumer overrides (Layer 3). Includes an ASCII-art layered
diagram (no SVG dependency) showing how the layers compose.

Documents the 24-token contract grouped by purpose, the two
attribute axes (data-theme, data-density), and the cascade order
that resolves when consumer overrides + dark mode + density
combine.

Cross-links to all 7 theming sub-pages plus the Token reference.

Part 3 of pretable docs PR 1.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>

Side-by-side description of Excel and Material 3 themes: visual
identity, when to use each, import statements. Excel: gray/technical/
dense, light-only, Aptos Narrow 11pt, Excel-green active cell.
Material 3: baseline scheme #6750A4, Roboto Flex, light + dark,
12dp medium shape, M3 surface tones.

Build-time switch is a single import swap. Cross-links to override
tokens, light/dark, density, custom themes.

Part 4 of pretable docs PR 1.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>

The override pattern explained: redefine --pretable-* values in
your :root, cascade source-order wins because your stylesheet
loads after the theme. No rebuild, no fork.

Four worked examples: tweak one accent (brand alignment), swap
entire palette (effectively a custom theme on top of Excel), change
corner radius, override density values. Plus token-group taxonomy
(surfaces / text / lines / state / accent / density / typography)
and specificity tips.

This is the "override story" the user flagged needs to be in /docs.

Part 5 of pretable docs PR 1.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>

Two patterns: React state-driven (user toggle button) and OS-respect
(prefers-color-scheme media query). Both wire data-theme="dark" on
<html> via a useEffect. Excel is light-only — flagged with a
blockquote pointing at custom themes for consumers who need dark
on Excel.

Documents independent composition with data-density attribute and
SSR considerations (cookie vs client-only).

Part 6 of pretable docs PR 1.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>

Three-tier density toggle (compact / standard / spacious) wired via
data-density attribute. Documents the per-theme natural default
(Excel compact, Material standard), the engine bridge through
useResolvedHeights + MutationObserver, prop-level override pattern,
composition with light/dark, and a localStorage persistence example.

Part 7 of pretable docs PR 1.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>

Authoring a theme file from scratch: copy excel.css or material.css
as a template, define all 24 --pretable-* tokens at :root, optionally
add [data-theme="dark"] for dark mode and [data-density="..."] for
non-default density tiers. Full code example for a custom brand
theme. When-to-use table comparing override-at-:root vs. custom
theme file vs. both.

Part 8 of pretable docs PR 1.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>

Two integration paths documented in one page (combined for v0.0.x;
can split later if either grows).

Tailwind v4: opt-in @pretable/ui/tailwind.css import registers
--color-pt-* / --font-pt-* shortcuts via @theme. Utilities like
bg-pt-bg-grid, text-pt-accent, font-pt-mono. Density and radius
intentionally excluded (no per-element utility analog).

CSS-in-JS: var(--pretable-*) works directly in styled-components,
emotion, vanilla-extract, etc. Runtime resolution means tokens
automatically reflect active theme + density + dark mode.

Part 9 of pretable docs PR 1.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>

Full reference for @pretable/ui's public theming contract. 24
tokens grouped: Surfaces (5), Text (3), Lines (3), State (4),
Accent (1), Density (6), Typography (2). Each row: name,
description, type (color / length / font), example value in Excel
+ Material 3 (light).

Density tokens marked "engine reads?" — only --pretable-row-height
and --pretable-header-height are read by JS; the other 22 are
CSS-only.

Plain markdown table for v0.0.x. If the contract grows past 30+
tokens later, upgrade to a sortable/filterable component.

Stability disclaimer documents the pre-1.0 token-rename freedom.

Part 10 of pretable docs PR 1.

Co-Authored-By: Claude Opus 4 (1M context) <noreply@anthropic.com>